Add Support for @oneOf Input Object Directive

Summary

This PR implements the @oneOf input object directive to match the GraphQL.js reference implementation (v16.11.0) and align with the GraphQL specification RFC #825.

The @oneOf directive enables input objects where exactly one field must be provided, addressing the common pattern of needing "input unions" in GraphQL schemas.

Implementation Details

Core Type System Changes

• InputObjectType: Added isOneOf property with proper type annotations, isOneOf() method, and validateOneOfConstraints() for spec compliance validation
• Directive: Added @oneOf directive definition with INPUT_OBJECT location
• Introspection: Added isOneOf field to __Type introspection object

Validation & Coercion

• OneOfInputObjectsRule: New validation rule ensuring exactly one field is provided in OneOf input objects
• Enhanced coercion validation: Added OneOf validation to Value::coerceInputValue() for runtime coercion errors
• Null value validation: Prevents explicitly null field values in OneOf inputs per spec requirements

GraphQL.js Compatibility & Spec Alignment

Matching GraphQL.js v16.11.0

This implementation aligns with the GraphQL.js reference implementation, following the same patterns for:

• Type system integration (isOneOf property)
• Introspection support (isOneOf field)
• Query validation (OneOf validation rule)
• Schema validation (OneOf constraint validation)

Enhanced Spec Compliance

Based on GraphQL.js PR #4195 and spec RFC #825, we've implemented additional validation:

• Runtime coercion validation: OneOf validation during input value coercion phase (matching PR #4195)
• Null field validation: Explicit null value detection for OneOf fields
• Comprehensive error messaging: Clear error messages for all OneOf validation scenarios

Test Coverage

This implementation includes comprehensive test coverage in tests/Type/OneOfInputObjectTest.php:

Basic OneOf Type Definition

• OneOf input object creation and configuration
• Schema-level validation of OneOf constraints
• Type introspection verification

Query Validation

• Valid OneOf input validation (exactly one field)
• Invalid input rejection (zero fields, multiple fields)
• Null value validation and error handling

Runtime Coercion Validation

• OneOf validation during Value::coerceInputValue()
• Proper error handling for invalid OneOf inputs
• Null field value detection and rejection

Edge Cases and Error Scenarios

• Complex OneOf validation scenarios
• Integration with existing GraphQL validation
• Backward compatibility verification

Corresponding GraphQL.js Tests

For reference, test coverage matches the GraphQL.js implementation found in:

• Execution tests: src/execution/__tests__/oneof-test.ts
• Coercion validation: src/utilities/__tests__/coerceInputValue-test.ts (lines ~309-411)
• Query validation: src/validation/__tests__/ValuesOfCorrectTypeRule-test.ts (lines ~877+)
• Type system validation: src/type/__tests__/validation-test.ts
• Introspection support: src/type/__tests__/introspection-test.ts

Breaking Changes

None. This is a purely additive feature that maintains full backward compatibility.

Migration Guide

No migration required. Existing schemas continue to work unchanged. To use OneOf:

$oneOfInput = new InputObjectType([
    'name' => 'SearchInput', 
    'fields' => [
        'byId' => Type::id(),
        'byName' => Type::string(),
        'byEmail' => Type::string(),
    ],
    'isOneOf' => true,
]);

Validation Results

• ✅ All 1,872 tests passing
• ✅ 21,070 assertions successful
• ✅ PHPStan analysis clean
• ✅ Spec-compliant implementation
• ✅ Runtime coercion validation included